Skip to content

[MRG] Fix batched GW/FGW envelope gradients with respect to marginals - #927

Open
xihaian251 wants to merge 1 commit into
PythonOT:masterfrom
xihaian251:fix/batched-gw-envelope-marginal-gradients
Open

xihaian251 wants to merge 1 commit into
PythonOT:masterfrom
xihaian251:fix/batched-gw-envelope-marginal-gradients

Conversation

@xihaian251

@xihaian251 xihaian251 commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Types of changes

  • Bug fix

Motivation and context

solve_gromov_batch(..., grad="envelope") detaches the transport plan but keeps a differentiable path to M, Ca, Cb on res.value; res.value_linear keeps only its path to M. The marginals a, b only enter through the detached solver, so res.value had no gradient path to them, for both plain GW and fused GW.

Independent 2×2 oracles (Wolfram quadruple-sum derivation + separate NumPy implementation): pure GW optimum G*=18/25 with ∂G/∂p=−14/5, ∂G/∂q=−8/5; fused GW (M=diag(3,3), α=1/2) optimum F*=51/100 with ∂F/∂p=−29/10, ∂F/∂q=−23/10. On unmodified master with reg=0.1, the solver reaches value=0.72 (marginal residual 3.7e-14) yet grad_p=grad_q=None; grad_M=(1−α)T* is already correct. Ten new tests fail on master and pass with the fix.

How has this been tested

  • Wolfram derivation from the raw quadruple sum, cross-checked by independent NumPy; the inner problem is correctly treated as entropy-regularized (not a pure LP), and the identity reg(u+v)−M_k = reg(log T_new − log T_prev) is proved from KKT.
  • Real-API negative controls for plain/fused GW with a forward gate before gradient comparison.
  • Convergence-gate stress tests found a decisive counterexample: tol=1e-2 yields the exact value=0.72, converged=True, marginal residual 2e-14, but a wrong gradient (−2.75084 vs −2.8). The gate now also requires marginal feasibility and stability of the centred sensitivities under one extra proximal projection; the counterexample is rejected.
  • Gauge invariance: the check compares centred sensitivities, invariant to u→u+c, v→v−c. A wrap adding +250/−250 to all returned potentials leaves gate flags, gradients and value unchanged (gradient diff ≤2e-15); the loose-tol counterexample stays rejected.
  • Scope: the extra projection is executed only for Torch grad="envelope". Measured call counts: Torch envelope 4, Torch detach/autodiff 3, NumPy all modes 3 — all non-target paths keep the original cost. Diagnostics (marginal_feasible, potentials_stable) are evaluated only on the Torch envelope marginal path and are None (not evaluated) elsewhere.
  • Batch semantics: conservative whole-batch rejection — if one sample fails any check, the marginal gradient is withheld for all samples; no zero gradient is emitted for an untrusted sample.
  • Batch VJP B=2/3/8 with mixed-sign cotangents: errors ≤1.2e-12, no leakage; float32 and POT_BACKEND_DISABLE_PYTORCH=1 checked.
  • pytest -q test/batch/: 134 passed. Ten new tests fail on master. With POT_BACKEND_DISABLE_PYTORCH=1, the target test file gives 30 passed / 14 skipped. Ruff 0.5.2, git diff --check clean. Full suite not run here; two pre-existing local environment limitations (BSP native-extension ABI mismatch, sandbox-blocked compiler probe) are documented, not claimed as passing.

Scope

Local to ot/batch/_quadratic.py, PyTorch only, first-order. Cost gradients and all forward values/plans are unchanged. The centred marginal gradient is registered only when the outer solve converged, the plan is marginally feasible, and the centred sensitivities are stable under one extra projection; the three checks are exposed in res.log and reduced over the whole batch. The stability check is an empirically validated criterion, not a mathematical guarantee for every GW problem. JAX/TensorFlow batch marginal gradients, higher-order differentiation, and unique sensitivities at active-set switching points are out of scope.

PR checklist

  • Read CONTRIBUTING.
  • Documentation (grad docstring) and RELEASES.md updated with precise limitations.
  • New tests cover the fix, gauge invariance, projection scope, batch semantics, and fail on master.

@codecov

codecov Bot commented Nov 17, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 99.58159% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 97.11%. Comparing base (7d51e72) to head (e840414).

Additional details and impacted files
@@            Coverage Diff             @@
##           master     #927      +/-   ##
==========================================
+ Coverage   97.09%   97.11%   +0.02%     
==========================================
  Files         130      130              
  Lines       27229    27464     +235     
==========================================
+ Hits        26437    26673     +236     
+ Misses        792      791       -1     
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant